19 września 2025Polski

Dowiedz się, jak efektywnie testować aplikacje FastAPI za pomocą TestClient. Poznaj najlepsze praktyki, zaawansowane techniki i rzeczywiste przykłady dla solidnych i niezawodnych API.

Mistrzowskie Testowanie FastAPI: Kompleksowy Przewodnik po TestClient

FastAPI stał się wiodącym frameworkiem do budowania wysokowydajnych API w Pythonie. Jego szybkość, łatwość użycia i automatyczna walidacja danych czynią go ulubieńcem wśród programistów na całym świecie. Jednak dobrze zbudowane API jest tak dobre, jak jego testy. Dokładne testowanie zapewnia, że Twoje API działa zgodnie z oczekiwaniami, pozostaje stabilne pod presją i może być z pewnością wdrażane na produkcję. Ten kompleksowy przewodnik koncentruje się na użyciu TestClient FastAPI do skutecznego testowania punktów końcowych API.

Dlaczego Testowanie Jest Ważne dla Aplikacji FastAPI?

Testowanie jest kluczowym krokiem w cyklu życia tworzenia oprogramowania. Pomaga:

Wcześnie identyfikować błędy: Wyłapuj błędy, zanim trafią na produkcję, oszczędzając czas i zasoby.
Zapewnić jakość kodu: Promuj dobrze ustrukturyzowany i łatwy w utrzymaniu kod.
Zapobiegać regresjom: Gwarantuj, że nowe zmiany nie psują istniejącej funkcjonalności.
Poprawić niezawodność API: Buduj zaufanie do stabilności i wydajności API.
Ułatwić współpracę: Zapewnij jasną dokumentację oczekiwanego zachowania dla innych programistów.

Wprowadzenie do TestClient FastAPI

FastAPI udostępnia wbudowany TestClient, który upraszcza proces testowania punktów końcowych API. TestClient działa jak lekki klient, który może wysyłać żądania do API bez uruchamiania pełnoprawnego serwera. To sprawia, że testowanie jest znacznie szybsze i wygodniejsze.

Kluczowe Funkcje TestClient:

Symuluje żądania HTTP: Pozwala wysyłać żądania GET, POST, PUT, DELETE i inne żądania HTTP do API.
Obsługuje serializację danych: Automatycznie serializuje dane żądania (np. ładunki JSON) i deserializuje dane odpowiedzi.
Udostępnia metody asercji: Oferuje wygodne metody weryfikacji kodu statusu, nagłówków i zawartości odpowiedzi.
Obsługuje testowanie asynchroniczne: Działa bezproblemowo z asynchroniczną naturą FastAPI.
Integruje się z frameworkami testowymi: Łatwo integruje się z popularnymi frameworkami testowymi Pythona, takimi jak pytest i unittest.

Konfiguracja Środowiska Testowego

Zanim zaczniesz testować, musisz skonfigurować środowisko testowe. Zazwyczaj obejmuje to zainstalowanie niezbędnych zależności i skonfigurowanie frameworka testowego.

Instalacja

Najpierw upewnij się, że masz zainstalowane FastAPI i pytest. Możesz je zainstalować za pomocą pip:

            pip install fastapi pytest httpx

httpx to klient HTTP, którego FastAPI używa "pod maską". Chociaż TestClient jest częścią FastAPI, posiadanie zainstalowanego httpx zapewnia płynne testowanie. Niektóre samouczki wspominają również o requests, jednak httpx jest bardziej zgodny z asynchroniczną naturą FastAPI.

Przykładowa Aplikacja FastAPI

Stwórzmy prostą aplikację FastAPI, której możemy użyć do testowania:

            from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
 name: str
 description: str | None = None
 price: float
 tax: float | None = None

@app.get("/")
async def read_root():
 return {"message": "Hello World"}

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str | None = None):
 return {"item_id": item_id, "q": q}

@app.post("/items/")
async def create_item(item: Item):
 return item

Zapisz ten kod jako main.py. Ta aplikacja definiuje trzy punkty końcowe:

/: Prosty punkt końcowy GET, który zwraca komunikat "Hello World".
/items/{item_id}: Punkt końcowy GET, który zwraca element na podstawie jego ID.
/items/: Punkt końcowy POST, który tworzy nowy element.

Pisanie Pierwszego Testu

Teraz, gdy masz aplikację FastAPI, możesz zacząć pisać testy za pomocą TestClient. Utwórz nowy plik o nazwie test_main.py w tym samym katalogu co main.py.

            from fastapi.testclient import TestClient
from .main import app

client = TestClient(app)

def test_read_root():
 response = client.get("/")
 assert response.status_code == 200
 assert response.json() == {"message": "Hello World"}

W tym teście:

Importujemy TestClient i instancję FastAPI app.
Tworzymy instancję TestClient, przekazując app.
Definiujemy funkcję testową test_read_root.
Wewnątrz funkcji testowej używamy client.get("/"), aby wysłać żądanie GET do głównego punktu końcowego.
Sprawdzamy, czy kod statusu odpowiedzi to 200 (OK).
Sprawdzamy, czy JSON odpowiedzi jest równy {"message": "Hello World"}.

Uruchamianie Testów za Pomocą pytest

Aby uruchomić testy, po prostu otwórz terminal w katalogu zawierającym plik test_main.py i uruchom następujące polecenie:

            pytest

pytest automatycznie wykryje i uruchomi wszystkie testy w Twoim projekcie. Powinieneś zobaczyć dane wyjściowe podobne do tego:

            ============================= test session starts ==============================
platform darwin -- Python 3.9.6, pytest-6.2.5, py-1.11.0, pluggy-1.0.0
rootdir: /path/to/your/project
collected 1 item

test_main.py .

============================== 1 passed in 0.01s ==============================

Testowanie Różnych Metod HTTP

TestClient obsługuje wszystkie standardowe metody HTTP, w tym GET, POST, PUT, DELETE i PATCH. Zobaczmy, jak testować każdą z tych metod.

Testowanie Żądań GET

Widzieliśmy już przykład testowania żądania GET w poprzedniej sekcji. Oto kolejny przykład, testujący punkt końcowy /items/{item_id}:

            def test_read_item():
 response = client.get("/items/1?q=test")
 assert response.status_code == 200
 assert response.json() == {"item_id": 1, "q": "test"}

Ten test wysyła żądanie GET do /items/1 z parametrem zapytania q=test. Następnie sprawdza, czy kod statusu odpowiedzi to 200 i czy JSON odpowiedzi zawiera oczekiwane dane.

Testowanie Żądań POST

Aby przetestować żądanie POST, musisz wysłać dane w treści żądania. TestClient automatycznie serializuje dane do JSON.

            def test_create_item():
 item_data = {"name": "Example Item", "description": "A test item", "price": 9.99, "tax": 1.00}
 response = client.post("/items/", json=item_data)
 assert response.status_code == 200
 assert response.json() == item_data

W tym teście:

Tworzymy słownik item_data zawierający dane dla nowego elementu.
Używamy client.post("/items/", json=item_data), aby wysłać żądanie POST do punktu końcowego /items/, przekazując item_data jako ładunek JSON.
Sprawdzamy, czy kod statusu odpowiedzi to 200 i czy JSON odpowiedzi pasuje do item_data.

Testowanie Żądań PUT, DELETE i PATCH

Testowanie żądań PUT, DELETE i PATCH jest podobne do testowania żądań POST. Po prostu używasz odpowiednich metod na TestClient:

            def test_update_item():
 item_data = {"name": "Updated Item", "description": "An updated test item", "price": 19.99, "tax": 2.00}
 response = client.put("/items/1", json=item_data)
 assert response.status_code == 200
 # Add assertions for the expected response

def test_delete_item():
 response = client.delete("/items/1")
 assert response.status_code == 200
 # Add assertions for the expected response

def test_patch_item():
 item_data = {"price": 29.99}
 response = client.patch("/items/1", json=item_data)
 assert response.status_code == 200
 # Add assertions for the expected response

Pamiętaj, aby dodać asercje, aby zweryfikować, czy odpowiedzi są zgodne z oczekiwaniami.

Zaawansowane Techniki Testowania

TestClient oferuje kilka zaawansowanych funkcji, które mogą pomóc w pisaniu bardziej kompleksowych i skutecznych testów.

Testowanie z Zależnościami

System wstrzykiwania zależności FastAPI pozwala łatwo wstrzykiwać zależności do punktów końcowych API. Podczas testowania możesz chcieć zastąpić te zależności, aby zapewnić mockowe lub specyficzne dla testów implementacje.

Na przykład, załóżmy, że Twoja aplikacja zależy od połączenia z bazą danych. Możesz zastąpić zależność bazy danych w testach, aby użyć bazy danych w pamięci:

            from typing import Annotated

from fastapi import Depends, FastAPI, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.orm import sessionmaker, declarative_base, Session

# Database Configuration
DATABASE_URL = "sqlite:///./test.db"  # In-memory database for testing
engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})
TestingSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

# Define User Model
class User(Base):
 __tablename__ = "users"

 id = Column(Integer, primary_key=True, index=True)
 username = Column(String, unique=True, index=True)
 password = Column(String)

Base.metadata.create_all(bind=engine)

# FastAPI App
app = FastAPI()

# Dependency to get the database session
def get_db():
 db = TestingSessionLocal()
 try:
 yield db
 finally:
 db.close()

# Endpoint to create a user
@app.post("/users/")
async def create_user(username: str, password: str, db: Session = Depends(get_db)):
 db_user = User(username=username, password=password)
 db.add(db_user)
 db.commit()
 db.refresh(db_user)
 return db_user

            from fastapi.testclient import TestClient
from .main import app, get_db, Base, engine, TestingSessionLocal

client = TestClient(app)

# Override the database dependency for testing

def override_get_db():
 try:
 db = TestingSessionLocal()
 yield db
 finally:
 db.close()

app.dependency_overrides[get_db] = override_get_db

def test_create_user():
 # First, ensure the tables are created, which may not happen by default
 Base.metadata.create_all(bind=engine) # important: create the tables in the test db
 response = client.post("/users/", params={"username": "testuser", "password": "password123"})
 assert response.status_code == 200
 assert response.json()["username"] == "testuser"

 # Clean up the override after the test if needed
app.dependency_overrides = {}

Ten przykład zastępuje zależność get_db funkcją specyficzną dla testów, która zwraca sesję do bazy danych SQLite w pamięci. Ważne: Tworzenie metadanych musi być jawnie wywołane, aby testowa baza danych działała poprawnie. Brak utworzenia tabeli spowoduje błędy związane z brakującymi tabelami.

Testowanie Kodu Asynchronicznego

FastAPI jest zbudowane jako asynchroniczne, więc często będziesz musiał testować kod asynchroniczny. TestClient bezproblemowo obsługuje testowanie asynchroniczne.

Aby przetestować asynchroniczny punkt końcowy, po prostu zdefiniuj funkcję testową jako async:

            import asyncio

from fastapi import FastAPI

app = FastAPI()

@app.get("/async")
async def async_endpoint():
 await asyncio.sleep(0.1) # Simulate some async operation
 return {"message": "Async Hello"}

            import pytest
from fastapi.testclient import TestClient
from .main import app

client = TestClient(app)

@pytest.mark.asyncio # Needed to be compatible with pytest-asyncio
async def test_async_endpoint():
 response = client.get("/async")
 assert response.status_code == 200
 assert response.json() == {"message": "Async Hello"}

Uwaga: Musisz zainstalować pytest-asyncio, aby używać @pytest.mark.asyncio: pip install pytest-asyncio. Musisz również upewnić się, że asyncio.get_event_loop() jest skonfigurowane, jeśli używasz starszych wersji pytest. Jeśli używasz pytest w wersji 8 lub nowszej, może to nie być wymagane.

Testowanie Przesyłania Plików

FastAPI ułatwia obsługę przesyłania plików. Aby przetestować przesyłanie plików, możesz użyć parametru files metod żądań TestClient.

            from fastapi import FastAPI, File, UploadFile
from typing import List

app = FastAPI()

@app.post("/files/")
async def create_files(files: List[bytes] = File()):
 return {"file_sizes": [len(file) for file in files]}

@app.post("/uploadfiles/")
async def create_upload_files(files: List[UploadFile]):
 return {"filenames": [file.filename for file in files]}

            from fastapi.testclient import TestClient
from .main import app
import io

client = TestClient(app)

def test_create_files():
 file_content = b"Test file content"
 files = [('files', ('test.txt', io.BytesIO(file_content), 'text/plain'))]
 response = client.post("/files/", files=files)
 assert response.status_code == 200
 assert response.json() == {"file_sizes": [len(file_content)]}

def test_create_upload_files():
 file_content = b"Test upload file content"
 files = [('files', ('test_upload.txt', io.BytesIO(file_content), 'text/plain'))]
 response = client.post("/uploadfiles/", files=files)
 assert response.status_code == 200
 assert response.json() == {"filenames": ["test_upload.txt"]}

W tym teście tworzymy fikcyjny plik za pomocą io.BytesIO i przekazujemy go do parametru files. Parametr files akceptuje listę krotek, gdzie każda krotka zawiera nazwę pola, nazwę pliku i zawartość pliku. Typ zawartości jest ważny dla poprawnej obsługi przez serwer.

Testowanie Obsługi Błędów

Ważne jest, aby przetestować, jak Twoje API obsługuje błędy. Możesz użyć TestClient, aby wysyłać nieprawidłowe żądania i sprawdzić, czy API zwraca poprawne odpowiedzi o błędach.

            from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int):
 if item_id > 100:
 raise HTTPException(status_code=400, detail="Item ID too large")
 return {"item_id": item_id}

            from fastapi.testclient import TestClient
from .main import app

client = TestClient(app)

def test_read_item_error():
 response = client.get("/items/101")
 assert response.status_code == 400
 assert response.json() == {"detail": "Item ID too large"}

Ten test wysyła żądanie GET do /items/101, które zgłasza HTTPException z kodem statusu 400. Test sprawdza, czy kod statusu odpowiedzi to 400 i czy JSON odpowiedzi zawiera oczekiwany komunikat o błędzie.

Testowanie Funkcji Bezpieczeństwa

Jeśli Twoje API używa uwierzytelniania lub autoryzacji, będziesz musiał również przetestować te funkcje bezpieczeństwa. TestClient pozwala ustawiać nagłówki i pliki cookie, aby symulować uwierzytelnione żądania.

            from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm

app = FastAPI()

# Security
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

@app.post("/token")
async def login(form_data: OAuth2PasswordRequestForm = Depends()):
 # Simulate authentication
 if form_data.username != "testuser" or form_data.password != "password123":
 raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Incorrect username or password")
 return {"access_token": "fake_token", "token_type": "bearer"}

@app.get("/protected")
async def protected_route(token: str = Depends(oauth2_scheme)):
 return {"message": "Protected data"}

            from fastapi.testclient import TestClient
from .main import app

client = TestClient(app)

def test_login():
 response = client.post("/token", data={"username": "testuser", "password": "password123"})
 assert response.status_code == 200
 assert "access_token" in response.json()

def test_protected_route():
 # First, get a token
 token_response = client.post("/token", data={"username": "testuser", "password": "password123"})
 token = token_response.json()["access_token"]

 # Then, use the token to access the protected route
 response = client.get("/protected", headers={"Authorization": f"Bearer {token}"}) # corrected format.
 assert response.status_code == 200
 assert response.json() == {"message": "Protected data"}

W tym przykładzie testujemy punkt końcowy logowania, a następnie używamy полученный token do uzyskania dostępu do chronionej trasy. Parametr headers metod żądań TestClient pozwala ustawiać niestandardowe nagłówki, w tym nagłówek Authorization dla tokenów okaziciela.

Najlepsze Praktyki Testowania FastAPI

Oto kilka najlepszych praktyk, których należy przestrzegać podczas testowania aplikacji FastAPI:

Pisz kompleksowe testy: Dąż do wysokiego pokrycia testami, aby zapewnić dokładne przetestowanie wszystkich części API.
Używaj opisowych nazw testów: Upewnij się, że nazwy testów wyraźnie wskazują, co test weryfikuje.
Postępuj zgodnie ze wzorcem Arrange-Act-Assert: Zorganizuj swoje testy w trzy odrębne fazy: Arrange (przygotuj dane testowe), Act (wykonaj testowaną akcję) i Assert (zweryfikuj wyniki).
Używaj obiektów mock: Mockuj zewnętrzne zależności, aby odizolować testy i uniknąć polegania na zewnętrznych systemach.
Testuj przypadki brzegowe: Testuj swoje API z nieprawidłowymi lub nieoczekiwanymi danymi wejściowymi, aby upewnić się, że obsługuje błędy w elegancki sposób.
Uruchamiaj testy często: Zintegruj testowanie ze swoim przepływem pracy programistycznej, aby wcześnie i często wychwytywać błędy.
Integruj z CI/CD: Zautomatyzuj swoje testy w potoku CI/CD, aby zapewnić, że wszystkie zmiany kodu są dokładnie testowane przed wdrożeniem na produkcję. Narzędzia takie jak Jenkins, GitLab CI, GitHub Actions lub CircleCI mogą być używane do osiągnięcia tego celu.

Przykład: Testowanie Internacjonalizacji (i18n)

Podczas tworzenia API dla globalnej publiczności kluczowa jest internacjonalizacja (i18n). Testowanie i18n obejmuje weryfikację, czy Twoje API poprawnie obsługuje wiele języków i regionów. Oto przykład, jak możesz testować i18n w aplikacji FastAPI:

            from fastapi import FastAPI, Header
from typing import Optional

app = FastAPI()

messages = {
 "en": {"greeting": "Hello, world!"},
 "fr": {"greeting": "Bonjour le monde !"},
 "es": {"greeting": "¡Hola Mundo!"},
}

@app.get("/")
async def read_root(accept_language: Optional[str] = Header(None)):
 lang = accept_language[:2] if accept_language else "en"
 if lang not in messages:
 lang = "en"
 return {"message": messages[lang]["greeting"]}

            from fastapi.testclient import TestClient
from .main import app

client = TestClient(app)

def test_read_root_en():
 response = client.get("/", headers={"Accept-Language": "en-US"})
 assert response.status_code == 200
 assert response.json() == {"message": "Hello, world!"}

def test_read_root_fr():
 response = client.get("/", headers={"Accept-Language": "fr-FR"})
 assert response.status_code == 200
 assert response.json() == {"message": "Bonjour le monde !"}

def test_read_root_es():
 response = client.get("/", headers={"Accept-Language": "es-ES"})
 assert response.status_code == 200
 assert response.json() == {"message": "¡Hola Mundo!"}

def test_read_root_default():
 response = client.get("/")
 assert response.status_code == 200
 assert response.json() == {"message": "Hello, world!"}

Ten przykład ustawia nagłówek Accept-Language, aby określić żądany język. API zwraca powitanie w określonym języku. Testowanie zapewnia, że API poprawnie obsługuje różne preferencje językowe. Jeśli nagłówek Accept-Language jest nieobecny, używany jest domyślny język "en".

Wniosek

Testowanie jest niezbędną częścią budowania solidnych i niezawodnych aplikacji FastAPI. TestClient zapewnia prosty i wygodny sposób testowania punktów końcowych API. Postępując zgodnie z najlepszymi praktykami opisanymi w tym przewodniku, możesz pisać kompleksowe testy, które zapewniają jakość i stabilność Twoich API. Od podstawowych żądań po zaawansowane techniki, takie jak wstrzykiwanie zależności i testowanie asynchroniczne, TestClient umożliwia tworzenie dobrze przetestowanego i łatwego w utrzymaniu kodu. Zaakceptuj testowanie jako podstawową część swojego przepływu pracy programistycznej, a zbudujesz API, które są zarówno potężne, jak i niezawodne dla użytkowników na całym świecie. Pamiętaj o znaczeniu integracji CI/CD w celu automatyzacji testowania i zapewnienia ciągłego zapewniania jakości.